javax.realtime
Class AsynchronouslyInterruptedException

java.lang.Object
  java.lang.Throwable
      java.lang.Exception
          java.lang.InterruptedException
              javax.realtime.AsynchronouslyInterruptedException

All Implemented Interfaces:

java.io.Serializable

Direct Known Subclasses:

Timed

public class AsynchronouslyInterruptedException

extends java.lang.InterruptedException

A special exception that is thrown in response to an attempt to asynchronously transfer the locus of control of a schedulable object.

A schedulable object that is executing a method or constructor, which is declared with an AsynchronouslyInterruptedException in its throws clause, can be asynchronously interrupted except when it is executing in the lexical scope of a synchronized statement within that method/constructor. As soon as the schedulable object leaves the lexical scope of the method by calling another method/constructor it may be asynchronously interrupted if the called method/constructor is asynchronously interruptible.

The asynchronous interrupt is generated for a real-time thread, t, when the t.interrupt() method is called or the fire method is called of an AIE for which t has a doInterruptible method call in progress.

The interrupt is generated for an AEH (or BAEH), h, if the fire method is called of an AIE for which h has a doInterruptible method call in progress.

If an asynchronous interrupt is generated when the target real-time thread/schedulable object is executing within an ATC-deferred section, the asynchronous interrupt becomes pending. A pending asynchronous interrupt is delivered when the target real-time thread/schedulable object next attempts to enter asynchronously interruptible code.

Asynchronous transfers of control (ATCs) are intended to allow long-running computations to be terminated without the overhead or latency of polling with Thread.interrupted().

When RealtimeThread.interrupt(), or AsynchronouslyInterruptedException.fire() is called, the AsynchronouslyInterruptedException is compared against any currently pending AsynchronouslyInterruptedException on the schedulable object. If there is none, or if the depth of the AsynchronouslyInterruptedException is less than the currently pending AsynchronouslyInterruptedException; (i.e., it is targeted at a less deeply nested method call), the new AsynchronouslyInterruptedException becomes the currently pending AsynchronouslyInterruptedException and the previously pending AsynchronouslyInterruptedException is discarded. Otherwise, the new AsynchronouslyInterruptedException is discarded.

When an AsynchronouslyInterruptedException is caught, the catch clause may invoke the clear() method on the AsynchronouslyInterruptedException in which it is interested to see if the exception matches the pending AsynchronouslyInterruptedException. If so, the pending AsynchronouslyInterruptedException is cleared for the schedulable object and clear returns true. Otherwise, the current AIE remains pending and clear returns false.

RealtimeThread.interrupt() generates a system-wide generic AsynchronouslyInterruptedException which will always propagate outward through interruptible methods until the generic AsynchronouslyInterruptedException is identified and handled. The pending state of the generic AIE is per-schedulable object.

Other sources (e.g., AsynchronouslyInterruptedException.fire() and Timed) will generate specific instances of AsynchronouslyInterruptedException which applications can identify and thus limit propagation.

AsyncEventHandler objects should interact with the ATC mechanisms via the Interruptible interface.

See Also:

Serialized Form

Field Summary

Fields inherited from class java.lang.Exception

Constructor Summary

AsynchronouslyInterruptedException()
Create an instance of AsynchronouslyInterruptedException.

Method Summary

(package private) boolean	clear() Atomically see if this is pending on the currently executing schedulable object, and if so, make it non-pending.
boolean	disable() Disable the throwing of this exception.
boolean	doInterruptible(Interruptible logic) Executes the run() method of the given Interruptible.
boolean	enable() Enable the throwing of this exception.
boolean	fire() Generate this exception if its doInterruptible() has been invoked and not completed.
static AsynchronouslyInterruptedException	getGeneric() Gets the singleton system generic AsynchronouslyInterruptedException that is generated when RealtimeThread.html.interrupt()is invoked.
boolean	isEnabled() Query the enabled status of this exception.

Methods inherited from class java.lang.Throwable

fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

AsynchronouslyInterruptedException

public AsynchronouslyInterruptedException()

Create an instance of AsynchronouslyInterruptedException.

Method Detail

getGeneric

public static AsynchronouslyInterruptedException getGeneric()

Gets the singleton system generic AsynchronouslyInterruptedException that is generated when RealtimeThread.html.interrupt()is invoked.

Not currently implemented

Returns:

The generic AsynchronouslyInterruptedException.

Throws:

java.lang.IllegalThreadStateException - if the current thread is a Java thread.

enable

public boolean enable()

Enable the throwing of this exception. This method is valid only when the caller has a call to doInterruptible() in progress. If invoked when no call to doInterruptible() is in progress, enable returns false and does nothing.

Not currently implemented

Returns:

True if this was disabled before the method was called and the call was invoked whilst the associated doInterruptible() is in progress. False: otherwise.

disable

public boolean disable()

Disable the throwing of this exception. If the fire method is called on this AIE whilst it is disabled, the fire is held pending and delivered as soon as the AIE is enabled and the interruptible code is within an AI-method. If an AIE is pending when the associated disable method is called, the AIE remains pending, and is delivered as soon as the AIE is enabled and the interruptible code is within an AI-method.

This method is valid only when the caller has a call to doInterruptible() in progress. If invoked when no call to doInterruptible() is in progress, disable returns false and does nothing.

Note: disabling the genericAIE associated with a real-time thread only affects the firing of that AIE. If the genericAIE is generated by the RealtimeThread.html.interrupt() mechanism, the AIE is delivered (unless the Interruptible code is in an AI-deferred region, in which case it is marked as pending and handled in the usual way).

Not currently implemented

Returns:

True if this was enabled before the method was called and the call was invoked with the associated doInterruptible() in progress. False: otherwise.

isEnabled

public boolean isEnabled()

Query the enabled status of this exception.

This method is valid only when the caller has a call to doInterruptible() in progress. If invoked when no call to doInterruptible() is in progress, enable returns false and does nothing.

Not currently implemented

Returns:

True if this is enabled and the method call was invoked in the context of the associated doInterruptible(). False otherwise.

fire

public boolean fire()

Generate this exception if its doInterruptible() has been invoked and not completed. If this is the only outstanding AIE on the current schedulable object, it becomes the current AIE. Otherwise, it only becomes the current AIE if it is at a less deeper level of nesting compared with the current outstanding AIE.

Not currently implemented

Returns:

True if this is not disabled and it has an invocation of a doInterruptible() in progress and there is no outstanding fire request. False otherwise.

doInterruptible

public boolean doInterruptible(Interruptible logic)

Executes the run() method of the given Interruptible. This method may be on the stack in exactly one Schedulable object. An attempt to invoke this method in a schedulable object while it is on the stack of another or the same schedulable object will cause an immediate return with a value of false.

The run() method of given Interruptible is always entered with the exception in the enabled state, but that state can be modified with enable() and disable() and the state can be observed with isEnabled().

The interruptAction method of the given Interruptible is called if any AIE is generated for the schedulable object executing the doInterruptible method. The generated AIE remains pending after the interruptAction method has finished if the pending AIE is not the AIE executing the doInterruptible method. If it is, the pending AIE is cleared.

Not currently implemented

Parameters:

logic - An instance of an Interruptible whose run() method will be called.

Returns:

True if the method call completed normally. False if another call to doInterruptible has not completed.

clear

boolean clear()

Atomically see if this is pending on the currently executing schedulable object, and if so, make it non-pending.

Not currently implemented

Returns:

True if this was pending. False if this was not pending.

Throws:

java.lang.IllegalThreadStateException - Thrown if called from a Java thread.